---
title: 文件上传
---

相较于聊天文本，文档文件能够承载大量的信息，例如学术报告、法律合同。受限于 LLM 自身仅能够支持文件或图片，难以获取文件内更加丰富的上下文信息，应用的使用者不得不手动复制粘贴大量信息与 LLM 对话，增加了许多不必要的使用成本。

文件上传功能允许将文件以 File variables 的形式在工作流应用中上传、解析、引用、和下载。**开发者现可轻松构建能理解和处理图片、音频、视频的复杂工作。**

### 应用场景

1. **文档分析**: 上传学术研究报告文件，LLM 可以快速总结要点，根据文件内容回答相关问题。
2. **代码审查**: 开发者上传代码文件，获得优化建议与 bug 检测。
3. **学习辅导**: 学生上传作业或学习资料，获得个性化的解释和指导。
4. **法律援助**: 上传完整的合同文本，由 LLM 协助审查条款，指出潜在风险。

### 文件上传与知识库的区别

文件上传和知识库都是为 LLM 提供额外上下文信息的方式，但它们在使用场景和功能上有明显区别：

1. **信息来源**：
   * 文件上传：允许终端用户在对话过程中动态上传文件，提供即时的、个性化的上下文信息。
   * 知识库：由应用开发者预先设置和管理，包含相对固定的信息集合。
2. **使用灵活性**：
   * 文件上传：更加灵活，用户可以根据具体需求上传不同类型的文件。
   * 知识库：内容相对固定，但可以被多个会话重复利用。
3. **信息处理**：
   * 文件上传：需要通过文档提取器或其他工具将文件内容转换为 LLM 可理解的文本。
   * 知识库：通常已经过预处理和索引，可以直接进行检索。
4. **应用场景**：
   * 文件上传：适用于需要处理用户特定文档的场景，如文档分析、个性化学习辅导等。
   * 知识库：适用于需要访问大量预设信息的场景，如客户服务、产品咨询等。
5. **数据持久性**：
   * 文件上传：通常为临时使用，不会长期存储在系统中。
   * 知识库：作为应用的一部分长期存在，可以持续更新和维护。

### 快速开始

Dify 支持在 [ChatFlow](/zh-hans/guides/workflow/key-concepts#chatflow-和-workflow) 和 [WorkFlow](/zh-hans/guides/workflow/concepts#chatflow-和-workflow) 类型应用中上传文件，并通过[变量](/zh-hans/guides/workflow/variables)交由 LLM 处理。应用开发者可以参考以下方法为应用开启文件上传功能：

* 在 Workflow 应用中：
  * 在 ["开始节点"](/zh-hans/guides/workflow/node/start) 添加文件变量
* 在 ChatFlow 应用中：
  * 在 ["附加功能"](/zh-hans/guides/workflow/additional-feature) 中开启文件上传，允许在聊天窗中直接上传文件
  * 在 ["开始节点"](/zh-hans/guides/workflow/node/start) 添加文件变量
  * 注意：这两种方法可以同时配置，它们是彼此独立的。附加功能中的文件上传设置（包括上传方式和数量限制）不会影响开始节点中的文件变量。例如只想通过开始节点创建文件变量，则无需开启附加功能中的文件上传功能。

这两种方法为应用提供了灵活的文件上传选项，以满足不同场景的需求。

#### File Types

file variables 和 array[file] variables 支持以下文件类型与格式：

| 文件类型 | 支持格式 |
|---------|---------|
| 文档 | TXT, MARKDOWN, PDF, HTML, XLSX, XLS, DOCX, CSV, EML, MSG, PPTX, PPT, XML, EPUB. |
| 图片 | JPG, JPEG, PNG, GIF, WEBP, SVG. |
| 音频 | MP3, M4A, WAV, WEBM, AMR. |
| 视频 | MP4, MOV, MPEG, MPGA. |
| 其他 | 自定义后缀名支持 |

#### 方法一：使用具备文件处理能力的 LLM

部分 LLMs（例如 [Claude 3.5 Sonnet](https://docs.anthropic.com/en/docs/build-with-claude/pdf-support)）已支持直接处理并分析文件内容，因此 LLM 节点的提示词已允许输入文件变量。

> 为了避免潜在异常，应用开发者在使用该文件变量前需前往 LLM 官网确认 LLM 支持何种文件类型。

1. 点击创建 Chatflow / Workflow 应用。
2. 添加 LLM 节点，选择具备文件分析能力的 LLM。
3. 在开始节点添加文件变量
4. 在 LLM 的系统提示词内输入文件变量。
5. 完成创建。

<Frame caption="具备识别文件的 LLM">
  <img src="https://assets-docs.dify.ai/2024/11/a7154e8966d979dcba13eac0a172ef89.png" alt="使用具备识别文件的 LLM 配置示意图" />
</Frame>

#### 方法二：在应用聊天框中开启文件上传（仅适用于 Chatflow）

1. 点击 Chatflow 应用右上角的 **"功能"** 按钮即可为应用添加更多功能。

   开启此功能后，应用使用者可以在应用对话的过程中随时上传并更新文件。最多支持同时上传 10 个文件，每个文件的大小上限为 15MB。

<Frame caption="文件上传功能">
  <img src="https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/20784cfa167417654a69c10e42e8271b.png" alt="Chatflow应用中文件上传功能的设置界面" />
</Frame>

开启该功能并不意味着赋予 LLM 直接读取文件的能力，还需要配备[**文档提取器**](/zh-hans/guides/workflow/node/doc-extractor)将文档解析为文本供 LLM 理解。

* 对于音频文件，可以使用 `gpt-4o-audio-preview` 等支持多模态输入的模型直接处理音频，无需额外的提取器。
* 对于视频和其他文件类型，暂无对应的提取器，需要应用开发者接入[外部工具](/zh-hans/guides/tools/extensions/api-based/api-based-extension)进行处理

2. 添加[文档提取器](/zh-hans/guides/workflow/node/doc-extractor)节点，在输入变量中选中 `sys.files` 变量。
3. 添加 LLM 节点，在系统提示词中选中文档提取器节点的输出变量。
4. 在末尾添加 "直接回复" 节点，填写 LLM 节点的输出变量。

<Frame caption="文件上传工作流">
  <img src="https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/bc7faa1f2ec9d26d3257f7bacc4b85d9.png" alt="包含文件上传的工作流示意图" />
</Frame>

开启后，用户可以在对话框中上传文件并进行对话。但通过此方式， LLM 应用并不具备记忆文件内容的能力，每次对话时需要上传文件。

<Frame caption="对话框中的文件上传">
  <img src="https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/b18af11da3f339c496193d9732906849.png" alt="对话框中上传文件的界面" />
</Frame>

若希望 LLM 能够在对话中记忆文件内容，请参考下文。

#### 方法三：通过添加文件变量开启文件上传功能

#### 1. 在"开始"节点添加文件变量

在应用的["开始"](/zh-hans/guides/workflow/node/start)节点内添加输入字段，选择 **"单文件"** 或 **"文件列表"** 字段类型的变量。

<iframe
  src="https://www.motionshot.app/walkthrough/6772ae35d65f37064a5d28d3/embed?fullscreen=1&hideAsSteps=1&hideCopy=1&hideDownload=1&hideSteps=1"
  width="70%"
  height="300px"
  frameborder="0"
  allowfullscreen
></iframe>

*   **单文件**

    仅允许应用使用者上传单个文件。
*   **文件列表**

    允许应用使用者单词批量上传多个文件。

> 为了便于操作，将使用单文件变量作为示例。

#### 文件解析

文件变量的使用方式主要分为两种：

1. 使用工具节点转换文件内容：
   * 对于文档类型的文件，可以使用"文档提取器"节点将文件内容转换为文本形式。
   * 这种方法适用于需要将文件内容解析为模型可理解的格式（如 string、array[string] 等）的情况。
2. 直接在 LLM 节点中使用文件变量：
   * 对于某些特定类型的文件（如图片），可以在 LLM 节点中直接使用文件变量。
   * 例如，对于图片类型的 file variables，可以在 LLM 节点中启用 vision 功能，然后在变量选择器中直接引用对应的文件变量。

选择哪种方式取决于文件类型和您的具体需求。接下来，我们将详细介绍这两种方法的具体操作步骤。

#### 2. 添加文档提取器节点

上传文件后将存储至单文件变量内，LLM 暂不支持直接读取变量中的文件。因此需要先添加 [**"文档提取器"**](/zh-hans/guides/workflow/node/doc-extractor)节点，从已上传的文档文件内提取内容并发送至 LLM 节点完成信息处理。

将"开始"节点内的文件变量作为 **"文档提取器"** 节点的输入变量。

<Frame caption="添加输入变量">
  <img src="https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/a42d183fa7ba38fa9c9d3bc772c79c29.png" alt="文档提取器节点添加输入变量的界面" />
</Frame>

将"文档提取器"节点的输出变量填写至 LLM 节点的系统提示词内。

<Frame caption="粘贴系统提示词">
  <img src="https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/f6ea094b30b240c999a4248d1fc21a1c.png" alt="LLM节点中粘贴系统提示词的界面" />
</Frame>

完成上述设置后，应用的使用者可以在 WebApp 内粘贴文件 URL 或上传本地文件，然后就文档内容与 LLM 展开互动。应用使用者可以在对话过程中随时替换文件，LLM 将获取最新的文件内容。

<Frame caption="粘贴 URL 进行对话">
  <img src="https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/f4d9056c2df7f94ce41d4f281b45a94e.png" alt="WebApp中粘贴URL进行对话的界面" />
</Frame>

**在 LLM 节点中引用文件变量**

对于某些特定类型的文件（如图片），可以在 LLM 节点中直接使用文件变量。这种方法特别适用于需要视觉分析的场景。以下是具体步骤：

1. 在 LLM 节点中，启用 vision 功能。这允许模型处理图像输入（模型需要支持 vision）。
2. 在 LLM 节点的变量选择器中，直接引用之前创建的文件变量如果是通过附加功能开启的文件上传，则选择 `sys.files` 变量。
3. 在系统提示词中，指导模型如何处理图像输入。例如，你可以要求模型描述图像内容或回答关于图像的问题。

下面是一个示例配置：

![](https://assets-docs.dify.ai/2025/04/ec247f5de4f59d4fb0c4ac25ce2fd96c.png)

需要注意的是，直接在 LLM 节点中使用文件变量时，我们需要确保文件变量仅包含图片文件，否则可能会导致错误。如果用户可能上传不同类型的文件，我们需要使用列表操作来进行过滤。

#### 文件下载

将文件变量放置到 answer 节点或者 end 节点中，当应用运行到该节点都时候将会在会话框中提供文件下载卡片。点击卡片即可下载文件。

![](https://assets-docs.dify.ai/2025/04/2ffc81675dee89d477cc461385501ddd.png)

### 进阶使用

若希望应用能够支持上传多种文件，例如允许用户同时上传文档文件、图片和音视频文件，此时需要在 "开始节点" 中添加 "文件列表" 变量，并通过"列表操作"节点针对不同的文件类型进行处理。详细说明请参考[列表操作](/zh-hans/guides/workflow/node/list-operator)节点。

<Frame caption="多种文件类型处理">
  <img src="https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/812d1b2f167065e17df8392b2cb3cc8a.png" alt="处理多种文件类型的工作流示意图" />
</Frame>

如需查看更多使用案例，请参考：[动手实验室 - 使用文件上传搭建文章理解助手](/zh-hans/workshop/intermediate/article-reader)

{/*
Contributing Section
DO NOT edit this section!
It will be automatically generated by the script.
*/}

<CardGroup cols="2">
    <Card
        title="编辑此页面"
        icon="pen-to-square"
        href="https://github.com/langgenius/dify-docs-mintlify/edit/main/zh-hans/guides/workflow/file-upload.mdx"
    >
        通过直接提交修改来帮助改进文档内容
    </Card>
    <Card
        title="提交问题"
        icon="github"
        href="https://github.com/langgenius/dify-docs-mintlify/issues/new?title=文档问题%3A%20upl&body=%23%23%20问题描述%0A%3C%21--%20请简要描述您发现的问题%20--%3E%0A%0A%23%23%20页面链接%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs-mintlify%2Fblob%2Fmain%2Fzh-hans/guides/workflow%2Ffile-upload.mdx%0A%0A%23%23%20建议修改%0A%3C%21--%20如果有具体的修改建议，请在此说明%20--%3E%0A%0A%3C%21--%20感谢您对文档质量的关注！%20--%3E"
    >
        发现错误或有改进建议？请提交问题反馈
    </Card>
</CardGroup>
